/*
 * Copyright 2014 François Rajchenbach.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/**
 * Provides a low-level API for formatting JSON expressions to character-output streams.
 * 
 * <h2>Format JSON expressions fluently</h2>
 * <p>This API is designed so that any JSON value can be written to a
 * {@link java.io.BufferedWriter} with a single chain of method calls, starting with
 * {@link qmd.rgo.format.JSONFormatter#writeTo(java.io.BufferedWriter)}.</p>
 * <p>At every step, the returned value of the latest method is an appropriate context object
 * with methods for adding valid elements to the JSON data structure:
 * <ul>
 *   <li>{@link qmd.rgo.format.ValueContext} is returned when the next step is to define the
 *       JSON value at the current location</li>
 *   <li>{@link qmd.rgo.format.ObjectContext} is returned when the next step is to add a member
 *       to the current JSON object, or to indicate that all members have been defined</li>
 *   <li>{@link qmd.rgo.format.ArrayContext} is returned when the next step is to add an item
 *       to the current JSON array, or to indicate that all items have been defined</li>
 *   <li>{@link qmd.rgo.format.FinalContext} is returned when the JSON expression is completed
 *       and no more method call can be chained</li>
 * </ul></p>
 * 
 * <h2>Example</h2>
 * <p>The following piece of code writes the JSON representation of a list of two
 * contact information cards, each with the first name, last name and email address of a person:</p>
 * <blockquote><pre>{@code JSONFormatter.writeTo(someWriter)
 *     .arrayContaining()
 *         .itemHaving().objectWith()
 *             .atEntry("firstName").value("John")
 *             .atEntry("lastName").value("Doe")
 *             .atEntry("email").value("john.doe@example.com")
 *             .noMoreEntry()
 *         .itemHaving().objectWith()
 *             .atEntry("firstName").value("Anne")
 *             .atEntry("lastName").value("O'Nymous")
 *             .atEntry("email").value("anne.onymous@example.com")
 *             .noMoreEntry()
 *         .noMoreItem()}</pre></blockquote>
 * 
 * @author François Rajchenbach
 * @since 1.0
 *
 */
package qmd.rgo.format;